import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import ThemedImage from "@theme/ThemedImage";
import InstallCommands from "@site/src/components/install";

# Self-Hosting

We provide a fully managed cloud instance of the Touca server at
https://app.touca.io. Since Touca is open-source, you have the option to install
it locally or deploy it to your own cloud infrastructure. We've made the process
straightforward and self-serve. [Join us on Discord](https://touca.io/discord)
or [send us an email](mailto:support@touca.io) if you need help or have any
questions.

:::info

Most of our paid plans include dedicated support and professional services for
deploying and upgrading self-hosted instances of Touca.

:::

We support two different self-hosted deployments of Touca:

1. You can host Touca as a set of Docker containers on a single machine. This
   setup uses Docker Compose and is most suitable for individuals and small
   engineering teams.
2. You can deploy Touca to your Kubernetes cluster using our Helm chart. This
   setup is suitable for engineering teams who are used to hosting third-party
   tools on Kubernetes.

Both deployments use MinIO, MongoDB, and Redis as service dependencies. If you
plan on using Touca at scale, we encourage you to upgrade to our paid deployment
setups that use DocumentDB, ElastiCache and S3 instead.

## Using Docker Compose

### Installing

You can install Touca server locally using either the Touca CLI (recommended) or
our `install.sh` script, or using `docker compose` directly.

<Tabs
  defaultValue="cli"
  groupId="self-hosted-install"
  values={[
    { label: "Using Touca CLI", value: "cli" },
    { label: "Using Bash Script", value: "bash" },
    { label: "Using Docker Compose", value: "compose" },
  ]}
>
  <TabItem value="cli">

The recommended way to manage Touca server is through our CLI.

<InstallCommands />

The [`touca server`](/cli/server) subcommand helps you install, upgrade, and
uninstall the Touca server, as well as to check its status and logs.

```bash
touca server install
```

This command uses `docker compose` to install the server into `~/.touca/server`
and run it. Once the install is over, navigate to Touca server and complete the
install wizard.

<ThemedImage
  sources={{
    light: "https://touca.io/docs/external/assets/touca-cli-server.light.gif",
    dark: "https://touca.io/docs/external/assets/touca-cli-server.dark.gif"
  }}
/>

  </TabItem>
  <TabItem value="bash">

```bash
/bin/bash -c "$(curl -fsSL https://touca.io/install.sh)"
```

This command uses `docker compose` to install the server into `~/.touca/server`
and run it. Once the install is over, navigate to Touca server and complete the
install wizard.

  </TabItem>
  <TabItem value="compose">

If you prefer using `docker compose` directly, clone the GitHub repository for
Touca, create local directories for the server dependencies and use the
following commands to install the server in the current working directory.

```bash
git clone git@github.com:trytouca/trytouca.git
cd trytouca
mkdir -p data/{minio,mongo,redis}
export UID_GID="$(id -u):$(id -g)"
docker compose -f ops/docker-compose.test.yml --project-directory . -p touca up -d
```

  </TabItem>
</Tabs>

### Uninstalling

<Tabs
  defaultValue="cli"
  groupId="self-hosted-install"
  values={[
    { label: "Using Touca CLI", value: "cli" },
    { label: "Using Bash Script", value: "bash" },
    { label: "Using Docker Compose", value: "compose" },
  ]}
>
  <TabItem value="cli">

To uninstall the server, you can use the following command to stop the running
containers and remove all server data from the filesystem.

```bash
touca server uninstall
```

  </TabItem>
  <TabItem value="bash">

To uninstall the server, you can use the following command to stop the running
containers and remove all server data from the filesystem.

```bash
/bin/bash -c "$(curl -fsSL https://touca.io/install.sh)" -- --uninstall
```

Note the extra `--` before `--uninstall`.

  </TabItem>
  <TabItem value="compose">

To uninstall the server, you can use the following command to stop the running
containers.

```bash
docker compose -f ops/docker-compose.prod.yml --project-directory . -p touca down
```

Remember to also remove directories for Touca server dependencies such as MinIO,
Mongo, and Redis.

  </TabItem>
</Tabs>

If you have any locally stored test results, you can manually remove them by
running `rm -r $HOME/.touca/results`.

## Using Helm

### Installing

You can use our Helm chart to deploy Touca to an existing Kubernetes cluster.

```bash
git clone git@github.com:trytouca/trytouca.git
cd ops/k8s/helm-chart
helm install <name> .
```

### Uninstalling

You can uninstall Touca the standard way:

```bash
helm uninstall <name>
```

:::info

Did we miss out a required step? We'd love to hear about your experience. Share
your thoughts with [support@touca.io](mailto:support@touca.io).

:::

## Post Install Setup

Once the server is running, navigate to the Touca web interface to complete a
one-time post-install setup that helps you create a primary user account.

<ThemedImage
  sources={{
    light:
      "https://touca.io/docs/external/assets/touca-server-install-wizard-name.light.png",
    dark: "https://touca.io/docs/external/assets/touca-server-install-wizard-name.dark.png"
  }}
/>

The user account your create during this process has special privileges that let
you manage server settings from the settings page and gives you exclusive rights
to promote other user accounts to server administrators so they can manage
server settings too.

<ThemedImage
  sources={{
    light:
      "https://touca.io/docs/external/assets/touca-server-install-wizard-account.light.png",
    dark: "https://touca.io/docs/external/assets/touca-server-install-wizard-account.dark.png"
  }}
/>

By default, self-hosted instances of Touca collect aggregate usage data and
report them to us once every day. See [Telemetry Reports](../telemetry) to learn
more about how this service works, what data we collect, and how you can disable
it through the server settings page.

<ThemedImage
  sources={{
    light:
      "https://touca.io/docs/external/assets/touca-server-install-wizard-telemetry.light.png",
    dark: "https://touca.io/docs/external/assets/touca-server-install-wizard-telemetry.dark.png"
  }}
/>

Once the post-install setup is complete, you can login to your self-hosted
instance using the primary account you created as part of the setup. While the
server setup process is officially complete, we strongly recommend that you
[configure a mail server](../integrations#mail-server-setup) for your instance
to enable sending email notifications. This optional step is essential for
[inviting other colleagues](../teams) to create an account and join your team.
